The fact that AuthenticationComponent::setIdentity() calls AuthenticationService::clearIdentity() has bitten me too.

Your proposed solution of replaceIdentity() which only updates the request attribute can also be problematic as it doesn't persist the changes. I have a use case where the identity needs to be checked and updated only on specific actions and once it's updated the updates should persist for the subsequent requests.

Maybe we need an option for AuthenticationComponent::setIdentity() or a new method which just skips the AuthenticationService::clearIdentity() call? I haven't checked but would preserve any current impersonation?

Another related issue with using AuthenticationComponent::setIdentity() is that it causes problems when you are also using the Authorization plugin. During normal flow the AuthorizationMiddleware decorates the identity object so that the identity implements the Authorization\IdentityInterface.

If you use AuthenticationComponent::setIdentity() that decoration is lost and if call any code which expects a Authorization\IdentityInterface instance it will generate an error. So we need a AuthenticationComponent::setIdentity() too (currently there's only AuthenticationComponent::buildIdentity() and then you have to update the request attribute yourself).

Pushed an update that addresses both points.

On the interface BC break (per @LordSimal):
Reverted the addition of buildIdentity() on AuthenticationServiceInterface and replaced it with a @method docblock annotation on the interface, so the call site stays type-aware without breaking third-party implementers.

On your "needs to persist for subsequent requests" point:
You're right that the original replaceIdentity() only swaps the in-request attribute and is not enough for the case where the refresh has to survive into the next request - it doesn't rewrite the session, and (as I found while testing) SessionAuthenticator::persistIdentity() deliberately won't overwrite an existing Auth slot, so just skipping clearIdentity() doesn't actually persist either.

So I went with option A: a new flag on setIdentity():

$this->Authentication->setIdentity($reloaded, preserveImpersonation: true);

Implementation: AuthenticationService::clearIdentity() gets an optional third parameter bool $stopImpersonation = true. The interface signature is untouched (PHP allows adding optional params on the implementation), so external AuthenticationServiceInterface implementers remain compatible. When set to false the impersonation slot survives, but each authenticator's clearIdentity() is still called so persistIdentity() can write the new identity into the session cleanly. The _successfulAuthenticator is also preserved in this path so same-request isImpersonating() calls keep working.

The two methods now have distinct intents:

• replaceIdentity($identity) - request-only swap, no session write (cheap, ideal for beforeFilter enrichment).
• setIdentity($identity, preserveImpersonation: true) - persist into session and keep impersonation alive (your use case).

New tests cover both the impersonation-preserving path and a regression test confirming the default setIdentity() flow still ends impersonation.

On the Authorization\IdentityInterface decoration loss:
Agreed that's a real adjacent papercut, but I'd prefer to handle it in a separate PR/issue so this one stays focused. Happy to open one if there isn't already.

Why I deferred it

There are three possible fixes and none are 1-line:

1. Make Authentication aware of Authorization. Have AuthenticationComponent::setIdentity() look up an Authorization\IdentityDecorator if the authorization service is on the request and re-wrap. Cleanest
   from the user's POV but creates a soft dependency on the authorization plugin — not great for a plugin that's supposed to work standalone.
2. Event hook. Dispatch an Authentication.identityReplaced event after writing the new identity attribute. The authorization plugin (or app code) listens and re-decorates. Decoupled, but requires
   changes in both plugins, and listeners need access to the authorization service.
3. Document the workaround. Tell users they need to manually re-decorate after setIdentity()/replaceIdentity():

$this->Authentication->setIdentity($reloaded);                                                                                                                                                            
if ($this->request->getAttribute('authorization')) {                   
    $identity = new IdentityDecorator(                                                                                                                                                                    
        $this->request->getAttribute('authorization'),                 
        $this->request->getAttribute('identity'),                                                                                                                                                         
    );                                                                 
    $this->setRequest($this->request->withAttribute('identity', $identity));                                                                                                                              
}  

3. Cheap to ship, but every consumer has to remember it.